GTAGS-CSCOPE(1)             General Commands Manual            GTAGS-CSCOPE(1)



[1mNAME[0m
       gtags-cscope - interactively examine a C program

[1mSYNOPSIS[0m
       [1mgtags-cscope [22m[-bCdehLlVv][-F file ][-012345678 [4mpattern[24m][-p n]

[1mDESCRIPTION[0m
       [1mgtags-cscope  [22mis  an  interactive, screen-oriented tool that allows the
       user to browse through source files for specified elements of code.

       [1mgtags-cscope [22mbuilds the symbol cross-reference the  first  time  it  is
       used on the source files for the program being browsed. On a subsequent
       invocation, [1mgtags-cscope [22mrebuilds the cross-reference only if a  source
       file  has  changed  or  the list of source files is different. When the
       cross-reference is rebuilt, it is updated  incrementally,  which  makes
       rebuilding faster than the initial build.

       [1mgtags-cscope  [22mis a tool which just borrows user interface of cscope; it
       is Global itself for the substance.

[1mOPTIONS[0m
       Some command line arguments can only occur as the only argument in  the
       execution  of  [1mgtags-cscope[22m.   They cause the program to just print out
       some output and exit immediately:

       [1m-h     [22mView the long usage help display.

       [1m-V     [22mPrint the version number of [1mgtags-cscope[22m.

       [1m--help [22mSame as [1m-h[0m

       [1m--version[0m
              Same as [1m-V[0m

       The following options can appear in any combination:

       [1m-a     [22mPrint absolute path names.

       [1m-b     [22mBuild the cross-reference only.

       [1m-C     [22mIgnore letter case when searching.

       [1m-d     [22mDo not update the cross-reference.

       [1m-e     [22mSuppress the '^e' command prompt between files.

       [1m-F [4m[22mfile[0m
              Read symbol reference lines from [4mfile[24m.  (A symbol reference file
              is  created  by  > and >>, and can also be read using the < com-
              mand, described under ``Issuing Subsequent Requests'', below.)

       [1m-i     [22mIgnore SIGINT signal in line-oriented mode.

       [1m-L     [22mDo a single search with line-oriented output when used with  the
              -num pattern option.

       [1m-l     [22mLine-oriented interface.  This option implies the [1m-d [22moption.

       [1m-[0-9] [4m[22mpattern[0m
              Go to input field [4mnum[24m (counting from 0) and find [4mpattern[24m.

       [1m-p [4m[22mn[24m   Display  the  last [4mn[24m file path components instead of the default
              (1). Use '0' to not display the file name at all.

       [1m-v     [22mBe more verbose in line-oriented mode.

[1mRequesting the initial search[0m
       After the cross-reference is  ready,  [1mgtags-cscope  [22mwill  display  this
       menu:

       Find this symbol:
       Find this global definition:
       Find functions called by this function (N/A):
       Find references of this function:
       Find this text string:
       Change this text string:
       Find this egrep pattern:
       Find this file:
       Find files #including this file:
       Find assignments to this symbol:

       Press  the  <Up> or <Down> keys repeatedly to move to the desired input
       field, type the text to search for, and then press the <Return> key.

[1mIssuing subsequent requests[0m
       If the search is successful, any of these single-character commands can
       be used:

       0-9a-zA-Z
              Edit the file referenced by the given line number.

       <Space>
              Display next set of matching lines.

       <Tab>  Alternate between the menu and the list of matching lines

       <Up>   Move to the previous menu item (if the cursor is in the menu) or
              move to the previous matching line (if  the  cursor  is  in  the
              matching line list).

       <Down> Move  to  the  next  menu item (if the cursor is in the menu) or
              move to the next matching line (if the cursor is in the matching
              line list).

       +      Display next set of matching lines.

       -      Display previous set of matching lines.

       ^e     Edit displayed files in order.

       >      Write the displayed list of lines to a file.

       >>     Append the displayed list of lines to a file.

       <      Read  lines from a file that is in symbol reference format (cre-
              ated by '>' or '>>'), just like the [1m-F [22moption.

       ^      Filter all lines through a shell command and display the result-
              ing lines, replacing the lines that were already there.

       |      Pipe  all  lines  to  a  shell  command and display them without
              changing them.

       ^g     Read lines from the result of the execution of [1mglobal[22m(1).

       At any time these single-character commands can also be used:

       <Return>
              Move to next input field.

       ^n     Move to next input field.

       ^p     Move to previous input field.

       ^y     Search with the last text typed.

       ^b     Move to previous input field and search pattern.

       ^f     Move to next input field and search pattern.

       ^c     Toggle ignore/use letter case  when  searching.  (When  ignoring
              letter case, a search for 'FILE' will match 'File' and 'file'.)

       ^r     Rebuild the cross-reference.

       !      Start  an  interactive  shell  (type  '^d'  to  return to [1mgtags-[0m
              [1mcscope[22m).

       ^l     Redraw the screen.

       ?      Give help information about [1mgtags-cscope [22mcommands.

       ^d     Exit [1mgtags-cscope[22m.

       NOTE: If the first character of the text to be searched for matches one
       of the above commands, escape it by typing a '\' (backslash) first.

       Substituting new text for old text

       After  the  text to be changed has been typed, [1mgtags-cscope [22mwill prompt
       for the new text, and then it will display the lines containing the old
       text.  Select  the lines to be changed with these single-character com-
       mands:

       0-9a-zA-Z
              Mark or unmark the line to be changed.

       *      Mark or unmark all displayed lines to be changed.

       <Space>
              Display next set of lines.

       +      Display next set of lines.

       -      Display previous set of lines.

       ^a     Mark or unmark all lines to be changed.

       ^d     Change the marked lines and exit.

       <Esc>  Exit without changing the marked lines.

       !      Start an interactive  shell  (type  '^d'  to  return  to  [1mgtags-[0m
              [1mcscope[22m).

       ^l     Redraw the screen.

       ?      Give help information about [1mgtags-cscope [22mcommands.

       Special keys
              If  your  terminal  has  arrow keys that work in [1mvi[22m, you can use
              them to move around the input fields. The up-arrow key is useful
              to  move  to the previous input field instead of using the <Tab>
              key repeatedly. If you have <CLEAR>, <NEXT>, or <PREV> keys they
              will act as the '^l', '+', and '-' commands, respectively.

[1mLine-Oriented interface[0m
       The  [1m-l [22moption lets you use [1mgtags-cscope [22mwhere a screen-oriented inter-
       face would not be useful, for  example,  from  another  screen-oriented
       program.

       [1mgtags-cscope  [22mwill prompt with '>>' when it is ready for an input line,
       which starts with the field number (counting from 0), immediately  fol-
       lowed  by the search pattern. For example, '1main' finds the definition
       of the 'main' function.

       If you just want a single search, instead of the [1m-l [22moption use  the  [1m-L[0m
       and [1m-num [4m[22mpattern[24m [4moptions,[24m [4mand[24m [4myou[24m [4mwon't[24m [4mget[24m [4mthe[24m [4m'>>'[24m [4mprompt.[0m

       For [1m-l[22m, [1mgtags-cscope [22moutputs the number of reference lines:
       cscope: 2 lines

       For each reference found, [1mgtags-cscope [22moutputs a line consisting of the
       file name, function name, line number, and line text, separated by spa-
       ces.  For example:
       main.c main 161 main(argc, argv)

       Note  that  the editor is not called to display a single reference, un-
       like the screen-oriented interface.

       You can use the 'c' command  to  toggle  ignore/use  letter  case  when
       searching.  (When  ignoring letter case, a search for 'FILE' will match
       'File' and 'file'.)

       You can use the 'r' command to rebuild the database.

       [1mgtags-cscope [22mwill quit when it detects end-of-file, or when  the  first
       character of an input line is '^d' or 'q'.

[1mENVIRONMENT VARIABLES[0m
       The following environment variables are of [1mcscope [22morigin.

       [1mCSCOPE_EDITOR[0m
              Overrides the [1mEDITOR [22mand [1mVIEWER [22mvariables.  Use this if you wish
              to use a different editor with [1mcscope  [22mthan  that  specified  by
              your [1mEDITOR[22m/[1mVIEWER [22mvariables.

       [1mCSCOPE_LINEFLAG[0m
              Format  of  the  line  number flag for your editor.  By default,
              [1mcscope [22minvokes your editor via  the  equivalent  of  'editor  +[4mN[0m
              [4mfile[24m',  where  [4mN[24m  is the line number that the editor should jump
              to.  This format is used by both [1memacs [22mand [1mvi[22m.  If  your  editor
              needs  something  different,  specify  it in this variable, with
              '%s' as a placeholder for the line number.  Eg: if  your  editor
              needs  to  be  invoked as 'editor -#103 [4mfile[24m' to go to line 103,
              set this variable to '-#%s'.

       [1mCSCOPE_LINEFLAG_AFTER_FILE[0m
              Set this variable to 'yes' if your editor needs  to  be  invoked
              with  the line number option after the filename to be edited. To
              continue the example from [1mCSCOPE_LINEFLAG[22m, above: if your editor
              needs  to see 'editor [4mfile[24m -#[4mnumber[24m', set this environment vari-
              able.  Users of most standard editors ([1mvi[22m, [1memacs[22m) do not need to
              set this variable.

       [1mEDITOR [22mPreferred editor, which defaults to [1mvi[22m.

       [1mHOME   [22mHome directory, which is automatically set at login.

       [1mSHELL  [22mPreferred shell, which defaults to [1msh[22m.

       [1mTERM   [22mTerminal type, which must be a screen terminal.

       [1mTERMINFO[0m
              Terminal  information directory full path name. If your terminal
              is not in the standard terminfo directory, see [1mcurses  [22mand  [1mter-[0m
              [1mminfo [22mfor how to make your own terminal description.

       [1mTMPDIR [22mTemporary file directory, which defaults to '/tmp'.

       [1mVIEWER [22mPreferred  file  display program (such as [1mless[22m), which overrides
              [1mEDITOR [22m(see above).

       The following environment variables are of [1mGlobal [22morigin.

       [1mGTAGSCONF[0m
              Configuration file.

       [1mGTAGSGLOBAL[0m
              If this variable is set, '$GTAGSGLOBAL' is used as the  name  of
              [1mglobal[22m(1). The default is [1mglobal[22m.

       [1mGTAGSGTAGS[0m
              If  this  variable  is set, '$GTAGSGTAGS' is used as the name of
              [1mgtags[22m(1). The default is [1mgtags[22m.

       [1mGTAGSDBPATH[0m
              The directory in which the tag files exist.  This value  is  ig-
              nored when [1mGTAGSROOT [22mis not defined.

       [1mGTAGSLABEL[0m
              Configuration label. The default is 'default'.

       [1mGTAGSLIBPATH[0m
              If  this  variable  is set, it is used as the path to search for
              library functions. If the specified tags is  not  found  in  the
              project,  [1mglobal  [22malso  searches  in  these  paths.   Since only
              'GTAGS' is targeted in the retrieval, this variable  is  ignored
              when [1m-r [22mor [1m-s [22mis specified.

       [1mGTAGSROOT[0m
              The root directory of the project.

       [1mMAKEOBJDIR[0m
              If  this  variable  is set, '$MAKEOBJDIR' is used as the name of
              BSD-style objdir. The default is 'obj'.

       [1mMAKEOBJDIRPREFIX[0m
              If this variable is set, '$MAKEOBJDIRPREFIX' is used as the pre-
              fix of BSD-style objdir. The default is '/usr/obj'.

[1mFILES[0m
       'GTAGS'
              Tag file for definitions.

       'GRTAGS'
              Tag file for references.

       'GPATH'
              Tag file for source files.

       'GTAGSROOT'
              If  environment  variable  [1mGTAGSROOT [22mis not set and file 'GTAGS-
              ROOT' exists in the same directory as 'GTAGS' then  [1mglobal  [22msets
              [1mGTAGSROOT [22mto the contents of the file.

       'gtags.conf', '$HOME/.globalrc'
              Configuration data for GNU Global.  See [1mgtags.conf[22m(5).

[1mSEE ALSO[0m
       [1mgtags[22m(1), [1mglobal[22m(1), [1mhtags[22m(1).

       GNU Global source code tag system
       (http://www.gnu.org/software/global/).

[1mBUG[0m
       The  function  field  of  the  display is almost <unknown> since [1mGlobal[0m
       doesn't recognize it.

       'Find functions called by this function' is not implemented.

[1mAUTHOR[0m
       Joe Steffen (original author) and others.

[1mHISTORY[0m
       [1mCscope [22mwas originally developed at Bell Labs in the  early  1980s,  and
       was  released  as  free  software  under the BSD license in April 2000.
       [1mGtags-cscope [22mis a derivative of [1mcscope [22mto use [1mGlobal [22mas  the  back-end.
       Its line-oriented interface was originally written in 2006, and was re-
       implemented in 2011 using [1mcscope [22mitself.



GNU Project                       March 2011                   GTAGS-CSCOPE(1)
